---
id: pinByHash
title: ''
---

## URL
```
https://<endpoint-api-host>/pinning/pinByHash
```

例如，“Decoo 上海” 的 *pinByHash* API URL 为：
```
https://api-sh.decoo-cloud.cn/pinning/pinByHash
```

## 描述
通过 CID 异步地上传 IPFS 文件到 Decoo。每一次 API 调用会生成一个 *pin job*，由 Decoo 后台定时处理。您可以调用 [pinJobs](pinning/pin-jobs.mdx) API 查询这些 Job 的状态。

:::note
为了确保文件能够成功地拉取并存储到 Decoo，该文件应该事先 Pin 在某个 IPFS 节点。
:::

## 请求类型
POST

## Headers
```
"UserAccessToken": "<YOUR_ACCESS_TOKEN>"
```

## Body

Request body 格式如下：
```json
{
  "hashToPin": "<文件 CID>",
  "secret": "<用户私钥针对文件 CID 生成的签名>"
}
```

在上传文件的同时，可以附加一些 metadata。这些 metadata 可以在调用 [pinList](pinning/pin-list.mdx) 查询文件列表时做为过滤条件。
```json
"decooMetadata": {
  "name": "<自定义文件名>"
}
```

## Response
```json
{
  "HashToPin": "<上传文件的 IPFS CID>",
  "JobId": "<Pin Job 的 ID>",
  "JobStatus": "<Pin Job 的当前状态。如果请求成功，当前状态应该为 'queued'>"
}
```

## Curl 请求示例
```sh
curl -X POST "https://api-sh.decoo-cloud.cn/pinning/pinByHash" \
  -H "UserAccessToken: <YOUR_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"hashToPin": "<HASH_TO_PIIN>", "decooMetadata": {"name": "我的文件"}}, "secret": "<DIGITITAL_SIGNATURE>"'
```
